HAL CRYP migration: List of applicable concepts

This section provides information about the HAL CRYP applicable architecture concepts.

Concepts for CRYP

Concept	Description
Separation of initialization and configuration functions	Provide a dedicated configuration for each algorithm, including only the parameters strictly required by that algorithm.
Removal and conversion of init structure to configuration structure	The init structure has been removed from the handle and converted into set configuration per algorithm function.
Renaming of the handle structure	The handle structure has been renamed to hal_aes_handle_t for AES peripheral and hal_cryp_handle_t for CRYP peripheral.
Renaming unitary init structures	The structure CRYP_InitTypeDef is no longer available, and has been replaced by hal_aes_gcm_config_t, hal_aes_ccm_config_t``for AES peripheral and ``hal_cryp_gcm_config_t, hal_cryp_ccm_config_t for CRYP peripheral.
Remove MspInit and MspDeInit callbacks	MspInit and MspDeInit are no longer available. They must be replaced by a user sequence to initializes and configures the CRYP or AES.
Unitary configuration APIs	New APIs are available to get and set AES/CRYP features.
Dedicated DMA link APIs replace generic __HAL_LINKDMA macro	The __HAL_LINKDMA macro is no longer provided: HAL_AES_SetInDMA and HAL_AES_SetOutDMA functions are provided to associate a HAL AES handle with a HAL DMA handle. HAL_CRYP_SetInDMA and HAL_CRYP_SetOutDMA functions are provided to associate a HAL CRYP handle with a HAL DMA handle.
Introduction of HAL user data set/get APIs	Two functions to set and get user data are available: HAL_AES_SetUserData and HAL_AES_GetUserData for AES peripheral. HAL_CRYP_SetUserData and HAL_CRYP_GetUserData for CRYP peripheral.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each CRYP event. These functions are used to register callback functions for different CRYP events.
Introduce specialized IRQ handlers	The IRQ handler is retained as a single, non‑partitioned routine. A dedicated compilation flag is used for each algorithm in order to minimize code footprint. Common error handling is preserved (these errors are considered blocking).
Revised and optimized HAL state machine	The CRYP and AES state machines have been redesigned to consistently track the operational states and transitions of the peripherals. AES peripheral states: HAL_AES_STATE_RESET HAL_AES_STATE_INIT HAL_AES_STATE_IDLE HAL_AES_STATE_ACTIVE HAL_AES_STATE_SUSPENDED CRYP peripheral states: HAL_CRYP_STATE_RESET HAL_CRYP_STATE_INIT HAL_CRYP_STATE_IDLE HAL_CRYP_STATE_ACTIVE HAL_CRYP_STATE_SUSPENDED
Revised and optimized HAL API status returns	The HAL CRYP/AES functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	The HAL error handling mechanisms have been redesigned to improve the detection, reporting, and handling of errors. This provides more detailed and consistent error information.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL CRYP driver have been removed and replaced by _t.
Replaced multi-line macros with inline functions	For the HAL CRYP driver, large macros have been replaced by inline functions to maintain code consistency, improve readability, and benefit from compiler optimization. Inline functions also offer better support for debugging and strict type management, reducing the risk of errors.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macros.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL CRYP header file remains and all macros, define statements, and functions from hal_cryp_ex.h have been moved to hal_cryp.h.
Replace the assert_param macro with ASSERT_DBG_PARAM, controlled by the USE_ASSERT_DBG_PARAM conditional.	Introduce a conditional compilation flag USE_ASSERT_DBG_PARAM to enable or disable debug parameter assertions, allowing for flexible debugging and validation.
Add ASSERT_DBG_STATE macro controlled by USE_ASSERT_DBG_STATE conditional.	Introduce a conditional compilation flag USE_ASSERT_DBG_STATE to enable or disable debug parameter assertions, allowing for flexible debugging and validation.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including CRYP/AES instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL AES/CRYP enums and struct start with hal_aes for AES peripheral and hal_cryp for CRYP peripheral.

Other HAL CRYP changes

Concept	Consideration
In HAL1 , the main limitation is that a single HAL AES driver is used for all device families, despite differing hardware implementations (AES, SAES, AES, and AES2 (for upcoming products)).	Provide a dedicated HAL driver for each peripheral: HAL AES driver: dedicated to the management of the AES and SAES peripheral. HAL CRYP driver: dedicated to the management of the CRYP peripheral.
Rework the suspend/resume mechanism to avoid saving context within the handle.	Remove the suspend/resume context parameters from the handle to reduce memory footprint. Introduce a dedicated context storage structure, used in conjunction with dedicated context save/restore APIs. Rationalize the context structure so that it contains only the parameters strictly required.
Use flags compilation to enable supporting the possible algorithms.	This approach will result in a significant optimization and simplification of the code base.
A new user data format is introduced, where buffers are of type void * and sizes are expressed in bytes. Endianness and alignment constraints for user data remain unchanged compared to HAL1 and will be detailed in the driver documentation. For migration purposes, user buffers used in HAL1 applications remain valid and compatible with HAL2.	The user is required to provide aligned buffers. The HAL driver verifies buffer alignment using assert, and then performs 32-bit pointer accesses across the entire buffer. The user must ensure consistency between data endianness and the configured swap mode: If no swap mode is configured, data must be provided in big-endian format. If data is provided in little-endian format, the user must appropriately configure the swap mode. Padding is handled at the word level. The driver pads only the missing whole words in a block with zeros, ensuring that four words are available to feed the data input register.
Rework the key configuration and setting.	Separate the key configuration from the global configuration.

HAL CRYP driver changes

In HAL2, the HAL CRYP driver is split into dedicated HAL drivers for each peripheral, as summarized in the table below

peripheral	HAL1 driver	HAL2 driver
AES SAES	HAL CRYP	HAL AES
CRYP	HAL CRYP	HAL CRYP